IRIX Base Documentation 2001 May/SGI IRIX Base Documentation 2001 May.iso/usr/share/catman/p_man/cat3/librw/rw_hashmap.z/rw_hashmap

Text File | 1998-10-30 | 21.3 KB | 463 lines

rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp((((3333CCCC++++++++))))                                              rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp((((3333CCCC++++++++))))



NNNNaaaammmmeeee
     rw_hashmap - Rogue Wave library class

SSSSyyyynnnnooooppppssssiiiissss
              #include <rw/rwstl/hashmap.h>
          rw_hashmap<K,V,Hash,EQ> map;




DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn
     Class rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp<<<<KKKK,,,,VVVV,,,,HHHHaaaasssshhhh,,,,EEEEQQQQ>>>> maintains a collection of mappings between
     KKKK and VVVV, implemented as a hash table of ppppaaaaiiiirrrr<<<<ccccoooonnnnsssstttt KKKK,,,,VVVV>>>> .  Pairs with
     duplicate keys are not allowed.  Two pairs having duplicate keys is the
     result of the EEEEQQQQ comparison, applied to the first element of each, is
     TTTTRRRRUUUUEEEE.  Since this is a vvvvaaaalllluuuueeee based collection, objects are ccccooooppppiiiieeeedddd into
     and out of the collection.  As with all classes that meet the ANSI
     aaaassssssssoooocccciiiiaaaattttiiiivvvveeee ccccoooonnnnttttaaaaiiiinnnneeeerrrr specification, rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp provides for iterators
     that reference its elements.  Operations that alter the contents of
     rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp may invalidate other iterators that reference the container.
     Since the contents of rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp are in pseudo-random order, the only
     iterator ranges that will usually make sense are the results of calling
     eeeeqqqquuuuaaaallll____rrrraaaannnnggggeeee((((kkkkeeeeyyyy)))), and the entire range from bbbbeeeeggggiiiinnnn(((()))) to eeeennnndddd(((()))).

PPPPeeeerrrrssssiiiisssstttteeeennnncccceeee
     None

PPPPuuuubbbblllliiiicccc TTTTyyyyppppeeeeddddeeeeffffssss
              typedef K                  key_type;
          typedef Hash               key_hash;
          typedef EQ                 key_equal;
          typedef pair<K,V>          value_type; // or ... "const K"
          typedef ((((uuuunnnnssssiiiiggggnnnneeeedddd))))         size_type; //from rw_slist
          typedef ((((iiiinnnntttt))))              difference_type; // from rw_slist
          typedef ((((vvvvaaaalllluuuueeee____ttttyyyyppppeeee&&&&))))      reference;
          typedef ((((ccccoooonnnnsssstttt vvvvaaaalllluuuueeee____ttttyyyyppppeeee&&&&)))) const_reference; //from rw_slist


     Iterators over rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp<<<<KKKK,,,,VVVV,,,,HHHHaaaasssshhhh,,,,EEEEQQQQ>>>> are forward iterators.

              typedef ((((ssssccccooooppppeeeedddd IIIItttteeeerrrraaaattttoooorrrr))))      iterator;
          typedef ((((ssssccccooooppppeeeedddd CCCCoooonnnnssssttttIIIItttteeeerrrraaaattttoooorrrr))))  const_iterator;



PPPPuuuubbbblllliiiicccc CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrrssss
              rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp<K,V,Hash,EQ>(size_type sz = 1024,
                                  const Hash& h = Hash(),
                                  const EQ& eq = EQ());


     Construct an empty rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp<<<<KKKK,,,,VVVV,,,,HHHHaaaasssshhhh,,,,EEEEQQQQ>>>> with sssszzzz slots, using hhhh as the



                                                                        PPPPaaaaggggeeee 1111






rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp((((3333CCCC++++++++))))                                              rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp((((3333CCCC++++++++))))



     hash object, and eeeeqqqq as the equality comparator.

              rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp<K,V,Hash,EQ>(const rw_hashmap<K,V,Hash,EQ>& map);


     Construct an rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp<<<<KKKK,,,,VVVV,,,,HHHHaaaasssshhhh,,,,EEEEQQQQ>>>> which is a copy of mmmmaaaapppp.  Each
     element from mmmmaaaapppp will be copied into self.

              rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp<K,V,Hash,EQ>(const_iterator first,
                                  const_iterator bound
                                  size_type sz=1024,
                                  const Hash& h = Hash(),
                                  const EQ& eq = EQ());


     Construct an rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp<<<<KKKK,,,,VVVV,,,,HHHHaaaasssshhhh,,,,EEEEQQQQ>>>> with sssszzzz slots, using hhhh as the hash
     object, and eeeeqqqq as the equality comparator, containing a copy of each pair
     referenced by the range starting with ffffiiiirrrrsssstttt and bounded by bbbboooouuuunnnndddd.

              rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp<K,V,Hash,EQ>(const value_type* first,
                                  const value_type* bound
                                  size_type sz=1024,
                                  const Hash& h = Hash(),
                                  const EQ& eq = EQ());


     Construct an rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp<<<<KKKK,,,,VVVV,,,,HHHHaaaasssshhhh,,,,EEEEQQQQ>>>> with sssszzzz slots, using hhhh as the hash
     object, and eeeeqqqq as the equality comparator, containing a copy of each pair
     referenced by the range starting with ffffiiiirrrrsssstttt and bounded by bbbboooouuuunnnndddd.  If
     there are items in the range for which the KKKK parts of the pairs match EEEEQQQQ,
     then only the first such item will be inserted into self.

PPPPuuuubbbblllliiiicccc DDDDeeeessssttttrrrruuuuccccttttoooorrrr
              ~~~~rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp<K,V,Hash,EQ>();


     The destructor releases the memory used by the container's
     implementation.

PPPPuuuubbbblllliiiicccc OOOOppppeeeerrrraaaattttoooorrrrssss
              rw_hashmap<K,V,Hash,EQ>&
          ooooppppeeeerrrraaaattttoooorrrr====(const rw_hashmap<K,V,Hash,EQ>& rhs);


     Sets self to have the same capacity, HHHHaaaasssshhhh and EEEEQQQQ as rrrrhhhhssss, removes all
     self's current contents, and replaces them with copies of the elements in
     rrrrhhhhssss.

              bool
          ooooppppeeeerrrraaaattttoooorrrr========(const rw_hashmap<K,V,Hash,EQ> & rhs) const;





                                                                        PPPPaaaaggggeeee 2222






rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp((((3333CCCC++++++++))))                                              rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp((((3333CCCC++++++++))))



     Returns true if self and rrrrhhhhssss have the same number of elements, and for
     each vvvvaaaalllluuuueeee____ttttyyyyppppeeee in self, there is a vvvvaaaalllluuuueeee____ttttyyyyppppeeee in rrrrhhhhssss that has a first
     part for which the EEEEQQQQ object in self returns true, and a second part for
     which ooooppppeeeerrrraaaattttoooorrrr========(((()))) returns true.  The need to test both parts means that
     this operator is slightly slower than the method eeeeqqqquuuuaaaallll____bbbbyyyy____kkkkeeeeyyyyssss(((())))
     described below.

              V&
          ooooppppeeeerrrraaaattttoooorrrr[[[[]]]](const key_type& key);


     Returns a reference to the VVVV part of a pair held in self which has a part
     EEEEQQQQ to kkkkeeeeyyyy, either by finding such a pair, or inserting one (in which case
     the reference is to an instance of VVVV created by its default constructor).

AAAAcccccccceeeessssssssoooorrrrssss
              iterator
          bbbbeeeeggggiiiinnnn();


     The iterator returned references the first item in self.  If self is
     empty, the iterator is equal to eeeennnndddd(((()))).  Note that because items are
     stored in pseudo-random order, this iterator might reference any item
     that has been stored in self.

              const_iterator
          bbbbeeeeggggiiiinnnn() const;


     The iterator returned references the first item in self.  If self is
     empty, the iterator is equal to eeeennnndddd(((()))).  Note that because items are
     stored in pseudo-random order, this iterator might reference any item
     that has been stored in self.

              iterator
          eeeennnndddd();


     The iterator returned marks the location "off the end" of self.  It may
     not be dereferenced.

              const_iterator
          eeeennnndddd() const;


     The iterator returned marks the location "off the end" of self.  It may
     not be dereferenced.

              pair<const_iterator, const_iterator>
          eeeeqqqquuuuaaaallll____rrrraaaannnnggggeeee(const key_type key) const;





                                                                        PPPPaaaaggggeeee 3333






rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp((((3333CCCC++++++++))))                                              rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp((((3333CCCC++++++++))))



     Returns ppppaaaaiiiirrrr<<<<ccccoooonnnnsssstttt____iiiitttteeeerrrraaaattttoooorrrr,,,, ccccoooonnnnsssstttt____iiiitttteeeerrrraaaattttoooorrrr>>>>((((lllloooowwwweeeerrrr____bbbboooouuuunnnndddd((((kkkkeeeeyyyy)))),,,,
     uuuuppppppppeeeerrrr____bbbboooouuuunnnndddd((((kkkkeeeeyyyy)))))))).  Upper and lower bound have special meaning for hash-
     based collections.  See discussion elsewhere.

              pair<iterator, iterator>
          eeeeqqqquuuuaaaallll____rrrraaaannnnggggeeee(const key_type key);


     Returns ppppaaaaiiiirrrr<<<<iiiitttteeeerrrraaaattttoooorrrr,,,, iiiitttteeeerrrraaaattttoooorrrr>>>>((((lllloooowwwweeeerrrr____bbbboooouuuunnnndddd((((kkkkeeeeyyyy)))),,,, uuuuppppppppeeeerrrr____bbbboooouuuunnnndddd((((kkkkeeeeyyyy)))))))).
     Upper and lower bound have special meaning for hash-based collections.
     See discussion elsewhere.

              const_iterator
          lllloooowwwweeeerrrr____bbbboooouuuunnnndddd(const key_type& key) const;


     Returns the lower bound of kkkkeeeeyyyy in self.  This has a special meaning for
     hash-based collections.  See discussion elsewhere.

              iterator
          lllloooowwwweeeerrrr____bbbboooouuuunnnndddd(const key_type& key);


     Returns the lower bound of kkkkeeeeyyyy in self.  This has a special meaning for
     hash-based collections.  See discussion elsewhere.

              const_iterator
          uuuuppppppppeeeerrrr____bbbboooouuuunnnndddd(const key_type& key) const;


     Returns the upper bound of kkkkeeeeyyyy in self.  This has a special meaning for
     hash-based collections.  See discussion elsewhere.

              iterator
          uuuuppppppppeeeerrrr____bbbboooouuuunnnndddd(const key_type& key);


     Returns the upper bound of kkkkeeeeyyyy in self.  This has a special meaning for
     hash-based collections.  See discussion elsewhere.

CCCCoooonnnnsssstttt PPPPuuuubbbblllliiiicccc MMMMeeeemmmmbbbbeeeerrrr FFFFuuuunnnnccccttttiiiioooonnnnssss
              size_type
          ccccaaaappppaaaacccciiiittttyyyy() const;


     Returns the number of slots in the hash table that self uses.

              bool
          eeeemmmmppppttttyyyy() const;


     Returns ttttrrrruuuueeee if self is empty.



                                                                        PPPPaaaaggggeeee 4444






rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp((((3333CCCC++++++++))))                                              rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp((((3333CCCC++++++++))))



              float
          ffffiiiillllllll____rrrraaaattttiiiioooo() const;


     Returns the result of calculating ssssiiiizzzzeeee(((())))////ccccaaaappppaaaacccciiiittttyyyy(((()))).

              size_type
          ssssiiiizzzzeeee() const;


     Returns the number of pairs currently held in self.

MMMMuuuuttttaaaattttoooorrrrssss
              void
          cccclllleeeeaaaarrrr();


     A synonym for eeeerrrraaaasssseeee((((bbbbeeeeggggiiiinnnn(((()))),,,,eeeennnndddd(((())))))));;;;

              size_type
          eeeerrrraaaasssseeee(const key_type& key);


     If there is a pair in self for which the first part is EEEEQQQQ to kkkkeeeeyyyy, that
     pair is removed, and 1111 is returned.  Otherwise, 0000 is returned.

              iterator
          eeeerrrraaaasssseeee(iterator iter);


     Removes the element referenced by iiiitttteeeerrrr and returns an iterator
     referencing the "next" element.  If iiiitttteeeerrrr does not reference an item in
     self, the result is undefined.

              iterator
          eeeerrrraaaasssseeee(iterator first, iterator bound);


     Removes each element in the range which begins with ffffiiiirrrrsssstttt and is bound by
     bbbboooouuuunnnndddd.  Returns an iterator referencing bbbboooouuuunnnndddd.  If ffffiiiirrrrsssstttt does not
     reference an item in self (and if ffffiiiirrrrsssstttt and bbbboooouuuunnnndddd are not equal), the
     effect is undefined.

              pair<iterator,bool>
          iiiinnnnsssseeeerrrrtttt(const value_type& val);


     If there is no pair in self with first part EEEEQQQQ to the first part of vvvvaaaallll
     then inserts vvvvaaaallll, returning a pair with an iterator referencing the new
     element and true.  Otherwise, returns a pair with an iterator referencing
     the matching vvvvaaaalllluuuueeee____ttttyyyyppppeeee and false.




                                                                        PPPPaaaaggggeeee 5555






rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp((((3333CCCC++++++++))))                                              rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp((((3333CCCC++++++++))))



              size_type
          iiiinnnnsssseeeerrrrtttt(iterator ignore, const value_type& val);


     If there is no pair in self with first part EEEEQQQQ to the first part of vvvvaaaallll
     then inserts vvvvaaaallll, returning 1111.  Otherwise, does nothing and returns 0000.
     Note that the first argument is provided only for conformance with the
     ANSI aaaassssssssoooocccciiiiaaaattttiiiivvvveeee ccccoooonnnnttttaaaaiiiinnnneeeerrrr specification, and is ignored by the method,
     since hash table look up can be done in constant time.

              size_type
          iiiinnnnsssseeeerrrrtttt(const value_type* first, const value_type* bound);


     For each element in the range beginning with ffffiiiirrrrsssstttt and bounded by bbbboooouuuunnnndddd,,,,
     if there is no pair in self with first part EEEEQQQQ to the first part of that
     element, the element is copied into self, or if there is such a pair, the
     element is skipped.  Returns the number of elements inserted.

              size_type
          iiiinnnnsssseeeerrrrtttt(const_iterator first, const_iterator bound);


     For each element in the range beginning with ffffiiiirrrrsssstttt and bounded by bbbboooouuuunnnndddd,,,,
     if there is no pair in self with first part EEEEQQQQ to the first part of that
     element, the element is copied into self, or if there is such a pair, the
     element is skipped.  Returns the number of elements inserted.

              void
          sssswwwwaaaapppp(rw_hashmap<K,V,Hash,EQ>& other);


     Exchanges the contents of self with ooootttthhhheeeerrrr including the HHHHaaaasssshhhh and EEEEQQQQ
     objects.  This method does not copy or destroy any of the items exchanged
     but exchanges the underlying hash tables.

SSSSppppeeeecccciiiiaaaallll MMMMeeeetttthhhhooooddddssss ffffoooorrrr MMMMaaaappppssss
              size_type
          ccccoooouuuunnnntttt(const key_type& key) const;


     Returns 1111 if self contains a pair with its first element EEEEQQQQ to kkkkeeeeyyyy, else
     0000.

              bool
          eeeeqqqquuuuaaaallll____bbbbyyyy____kkkkeeeeyyyyssss(const rw_hashmap<K,V,Hash,EQ>& rhs) const;


     Returns true if self and rrrrhhhhssss have the same size, and if for each
     vvvvaaaalllluuuueeee____ttttyyyyppppeeee in self, there is a vvvvaaaalllluuuueeee____ttttyyyyppppeeee in rrrrhhhhssss such that the EEEEQQQQ object
     in self returns true when called for the first parts of those pairs.
     Note that this method does not compare the VVVV (second) part of the pair of



                                                                        PPPPaaaaggggeeee 6666






rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp((((3333CCCC++++++++))))                                              rrrrwwww____hhhhaaaasssshhhhmmmmaaaapppp((((3333CCCC++++++++))))



     the items, so it will run slightly faster than ooooppppeeeerrrraaaattttoooorrrr========(((()))).

              const_iterator
          ffffiiiinnnndddd(const key_type& key) const;


     Returns a const_iterator referencing the pair with kkkkeeeeyyyy as its first
     element if such a pair is contained in self, else returns eeeennnndddd(((()))).

              iterator
          ffffiiiinnnndddd(const key_type& key);


     Returns an iterator referencing the pair with kkkkeeeeyyyy as its first element,
     if such a pair is contained in self, else returns eeeennnndddd(((()))).

              void
          rrrreeeessssiiiizzzzeeee(size_type sz);


     Resizes self's hash table to have sssszzzz slots; and re-hashes all self's
     elements into the new table.  Can be very expensive if self holds many
     elements.
































                                                                        PPPPaaaaggggeeee 7777